﻿<!DOCTYPE html>
<html lang="en">
<head>
  <meta content="text/html; charset=utf-8" http-equiv="content-type">
  <title>JavaScript Preflight Injection</title>
<style type="text/css">
   pre.idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
   pre.idl :link, pre.idl :visited { color:inherit; background:transparent }
   pre code { color:inherit; background:transparent }
   div.example { margin-left:1em; padding-left:1em; border-left:double; color:#222; background:#fcfcfc }
   .note { margin-left:2em; font-weight:bold; font-style:italic; color:#008000 }
   p.note::before { content:"Note: " }
   .XXX { padding:.5em; border:solid #f00 }
   p.XXX::before { content:"Issue: " }
   dl.switch { padding-left:2em }
   dl.switch > dt { text-indent:-1.5em }
   dl.switch > dt:before { content:'\21AA'; padding:0 0.5em 0 0; display:inline-block; width:1em; text-align:right; line-height:0.5em }
   dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
   dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
   dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
   dl.domintro dd p { margin: 0.5em 0; }
   dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: red; border: solid 2px; background: white; padding: 0 0.25em; }
   em.ct { text-transform:lowercase; font-variant:small-caps; font-style:normal }
   dfn { font-weight:bold; font-style:normal }
   code { color:orangered }
   code :link, code :visited { color:inherit }
   hr:not(.top) { display:block; background:none; border:none; padding:0; margin:2em 0; height:auto }
   table { border-collapse:collapse; border-style:hidden hidden none hidden }
   table thead { border-bottom:solid }
   table tbody th:first-child { border-left:solid }
   table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
   div.parameters { display:block; margin-left: 25px;}
   div.parameterDefinition { display:block; margin-left: 25px;}
   div.methods { display:block; margin-top:30px; margin-left :25px;}
  </style>
  <link href="https://www.w3.org/StyleSheets/TR/W3C-ED.css" rel="stylesheet" type="text/css">
</head>

<body class="draft">

<div class="head">
<hgroup>
<h1>JavaScript Preflight Injection</h1>
<h2 class="no-num no-toc" id="editors-draft-march-19-2012">Editor's Draft August 30, 2013</h2>
</hgroup>
<dl>
  <dt>This version:</dt>
    <dd><a
      href="https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html">https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html</a></dd>
  <dt>Latest version:</dt>
    <dd><a
      href="https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html">https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html</a></dd>
  <dt>Latest Editor's Draft:</dt>
    <dd><a
      href="https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html">https://w3c.github.io/web-performance/specs/JSPreflightInjection/Overview.html</a></dd>
  <dt>Editors:</dt>
    <dd class="vcard"><span class="fn">Alois Reitbauer</span>, <span
      class="org">Compuware Corp.</span>, &lt;<a
      class="email" href="mailto:alois.reitbauer@compuware.com">alois.reitbauer@compuware.com</a>&gt; </dd>
</dl>

   <p class=copyright><a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
    &copy; 2012 <a href="http://www.w3.org/"><abbr title="World Wide Web
    Consortium">W3C</abbr></a><sup>&reg;</sup> (<a
    href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute
    of Technology">MIT</abbr></a>, <a
    href="http://www.ercim.eu/"><abbr title="European Research Consortium
    for Informatics and Mathematics">ERCIM</abbr></a>, <a
    href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
    <a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>

    and <a
    href="http://www.w3.org/Consortium/Legal/copyright-documents">document
    use</a> rules apply.</p>

   <hr class='top'>
</div>

<h2 class="no-num no-toc" id="abstract">Abstract</h2>

<p>This specification defines an HTTP-based  mechanism for JavaScript monitoring code which leverages other performance APIs (like Resource Timing).</p>

<h2 class="no-num no-toc" id="status-of-this-document">Status of this
document</h2>

  <p><em>This section describes the status of this document at the time of
   its publication. Other documents may supersede this document. A list of
   current W3C publications and the latest revision of this technical report
   can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
   index</a> at http://www.w3.org/TR/.</em></p>

<p>This is a <strong>work in progress</strong> and may change without any
notices. </p>

<p>Please send comments
   to <a href="mailto:public-web-perf@w3.org?subject=%5BNavigationTiming2%5D%20">public-web-perf@w3.org</a>
   (<a href="http://lists.w3.org/Archives/Public/public-web-perf/">archived</a>)
   with <samp>[JSPreflight]</samp> at the start of the subject line.</p>

<p>This document is produced by
   the <a href="http://www.w3.org/2010/webperf/">Web Performance</a>
   Working Group. The Web Performance Working Group is part of
   the <a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients
   Activity</a> in the
   W3C <a href="http://www.w3.org/Interaction/">Interaction
   Domain</a>.

<p>Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced
or obsoleted by other documents at any time. It is inappropriate to
cite this document as other than work in progress. </p>

<p>This document was produced by a group operating under
   the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
   February 2004 W3C Patent Policy</a>. W3C maintains
   a <a href="http://www.w3.org/2004/01/pp-impl/45211/status"
   rel="disclosure">public list of any patent disclosures</a> made in
   connection with the deliverables of the group; that page also
   includes instructions for disclosing a patent. An individual who
   has actual knowledge of a patent which the individual believes
   contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
   Claim(s)</a> must disclose the information in accordance
   with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
   6 of the W3C Patent Policy</a>.</p>


<h2 class="no-num no-toc" id="table-of-contents">Table of Contents</h2>
<!--begin-toc-->
<ol class="toc">
  <li><a href="#introduction"><span class="secno">1
  </span>Introduction</a></li>
  <li><a href="#conformance-requirements"><span class="secno">2
    </span>Conformance requirements</a></li>
  <li><a href="#terminology"><span class="secno">3 </span>Terminology</a></li>
  <li><a href="#sec-preflight-injection"><span class="secno">4 JavaScript Preflight Injection</a> 
    <ol class="toc">
      <li><a href="#sec-Introduction"><span class="secno">4.1 </span> Introduction</a></li>
      <li><a href="#sec-script-execution"><span class="secno">4.2 </span>Executing Preflight Scripts</a></li>      
      <li><a href="#vendor-prefixes"><span class="secno">4.3 </span>Vendor Prefixes</a></li>
      <li><a href="#processing-model"><span class="secno">4.4 </span>Processing Model</a></li>
    </ol>
   </li>
  <li><a href="#privacy-security"><span class="secno">5 </span>Privacy and Security</a>
  </li>
  <li><a href="#references"><span class="secno">6 </span>References</a>
  </li>
</ol>
<!--end-toc-->

<h2 id="introduction"><span class="secno">1 </span>Introduction</h2>

<p>
    This section is non-normative.
</p>


<p>
Performance data collection is well supported by Navigation Timing, Resource Timng and Navigation Error Logging. The collection, processing of the data as well as the data transfer to a monitoring server is left to application owners. The currently used approach is to add a script to the page which then takes care of the above tasks as shown below. 
</p>

<div class="example">
    <p>
  For example, an HTML page that wants to load a JavaScript file which processes and sends Performance Timeline data will be integrated into a page using a JavaScript tag in the head section of the page.  
    </p>
    <pre>
     &lt;html&gt;
       &lt;head&gt;
          &lt;script type="text/javascript" src="./monitoring.js" &gt;&lt;/script&gt;
       &lt;/head&gt;
       ....
    </pre>
</div>

While this approach works in simple cases it is rather limited and may even result in errors. 


<ul>
 <li> The manual injection approach can only be used for site where a user can modify the sources. If this is not the case, the benefits of Navigation or Resource Timing cannot be leveraged. Examples are Third
       Party Software Applications (like a CRH system) which is crucial to business operations, but cannot be monitored. </li>
 <li> When manual injection does not apply, the script has to be injected automatically - typically by a web server plugin. While this approach works it adds an unnecessary risk of breaking the HTML code
      of a page. An example are HTML base tags. A monitoring script has to be injected after these tags as it otherwise breaks the page. However, these tags might not appear right at the beginning of a page. The injection mechanism therefore cannnot reliably inject early on the page. This, however, is required to ensure that monitoring code is properly registered for events (like unbeforeUnload or onresourcetimingbufferfull).
 <li> The script injection approach cannot be used in case the page fails to load. Navigation Error Logging information therefore cannot be transferred using this mechanism </li>
</ul>


<p>
To address the need for a better mechanism to add analytics logic to web pages the <a href="">Javascript Preflight Injection</a> specification 
defines a standardized and reliable approach to load JavaScript for analytics purposes without impacting the loading of the actual web page.
</p>  

<h2 id="conformance-requirements"><span class="secno">2 </span>Conformance
requirements</h2>

<p>All diagrams, examples, and notes in this specification are non-normative,
as are all sections explicitly marked non-normative. Everything else in this
specification is normative. </p>

<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document
are to be interpreted as described in <a href="#rfc2119">RFC 2119</a>.
For readability, these words do not appear in all uppercase letters in this specification.</p>

<p>Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these steps")
are to be interpreted with the meaning of the key word ("must", "should",
"may", etc) used in introducing the algorithm. </p>

<p>Some conformance requirements are phrased as requirements on attributes,
methods or objects. Such requirements are to be interpreted as requirements
on user agents. </p>

<p>Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the end result is equivalent. (In
particular, the algorithms defined in this specification are intended to be
easy to follow, and not intended to be performant.) </p>

    <p>The IDL fragments in this specification must be interpreted as
    required for conforming IDL fragments, as described in the Web IDL
    specification. <a href="#WebIDL">[Web IDL]</a></p>

<h2 id="terminology"><span class="secno">3 </span>Terminology</h2>

<p>The construction "a <code title="">Foo</code> object", where <code
title="">Foo</code> is actually an interface, is sometimes used instead of
the more accurate "an object implementing the interface <code
title="">Foo</code>". </p>

<p>The term "navigation" refers to the act of
<a href="http://www.w3.org/TR/html5/browsers.html#navigate">navigating</a>.</p>

<p>The term "JavaScript" is used to refer to
<a href="#ECMA262">ECMA-262</a>,
rather than the official term ECMAScript, since the term JavaScript is more widely known.</p>

<h2 id="sec-preflight-injection"><span class="secno">4 </span>JavaScript Preflight Injection</h2>

<h3 id="sec-Introduction"><span class="secno">4.1 </span> Introduction</h3>
<p>This section is non-normative.</p>

<p>
	This specification defines the main steps involved in JavaScript Preflight Injection. The mechanism is heavily based on the behaviour of cookies.
</P>

<h3 id="sec-Capability"><span class="secno"></span> Capability Communication</h3>

<p>
The first interaction between browser and server is part of the HTTP request. The browser has to communicate that it supports PreFlight Injection.


<div class="example">
  <p>
  The Accept-Preflight header is set indicating that the browser supports preflight JavaScript injection.  
  </p>  
  <pre>
        GET /index.html HTTP/1.1
        Host: www.example.com
        Accept-Preflight: true
  </pre>
</div>
</p>  


<h3 id="sec-Setting"><span class="secno"></span> Setting Preflight Injection</h3>

<div class="example">
  <p>
  The server sets a preflight JavaScript Cookie for the domain <a href="www.example.com">www.example.com</a>
  </p>  
  <pre>
        HTTP/1.1 200 OK
        Date: Thu, 24 Jan 2013 05:46:54 GMT
        Content-Length: 2291
        Content-Type: text/html
        Set-Preflight-Cookie: /monitoring.js;domain=www.example.com;path=/;max-age=250000
  </pre>
</div>
</p>  


<h3 id="sec-Setting"><span class="secno"></span> Communicating current Preflight settings </h3>

<div class="example">
  <p>
  The Preflight Cookie header is sent back to indicate that the browser has set a preflight JavaScript file.
  </p>  
  <pre>
        GET /index.html HTTP/1.1
        Host: www.example.com
        Preflight-Cookie: /monitoring.js
  </pre>
</div>
</p> 

<h3 id="sec-Setting"><span class="secno"></span> Clearing Preflight Injection </h3>

<div class="example">
  <p>
  The Set-PreflightCookie: is set to remove a script from preflight injection.
  </p>  
  <pre>
        GET /index.html HTTP/1.1
        Host: www.example.com
        Set-Preflight-Cookie: /monitoring.js;delete
  </pre>
</div>
</p> 


<h3 id="sec-script-execution"><span class="secno">4.2</span> Executing Preflight Scripts </h3>

<p>
Preflight scripts are executed when the document object is created or when the page load has failed and a Navigation Error has been created.
</p>  


<h3 id="vendor-prefixes"><span class="secno">4.3 </span>Vendor Prefixes</h3>
<p>Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed,
e.g., for experimental purposes, vendors MUST use the following extension mechanisms:</p>

<ul>
    <li>
        If the extension to be added is an errorType, the new type MUST return a DOMString in the following naming convention: [vendorprefix]_[preflight], where [vendorprefix] is a name
        that identifies the vendor and [errorType] is the name of the error.
    </li>
</ul>




<h3 id="processing-model"><span class="secno">4.4 </span>Processing Model</h3>


<p>This section is non-normative.</p>

<ol>
  <li>When the browser receives a new document it checks for the JavaScript Preflight header. </li>
  <li>If the browser finds a Preflight header or has a Preflight Coookie set for the documents domain it starts downloading it immediately. </li> 
  <li>If the preflight JavaScript is cached, it takes it from the cache. Otherwise it downloads it like a normal resource. </li>
  <li>If the document fails to load (e.g. due to a DNS error) the script gets executed as soon as it is available. </li> 
  <li>If the document loads successfully the script is executed as soons as the document object is constructed</li>
  <li>If the Preflight scirpt takes longer to load, the browser waits with all other JavaScript execution until the Preflight script is executed </li>
</ol>  

<p>
<b>Note: </b> Possibly we need a flag where a preflight script can specify an async attribute indicating it does not need to be executed before any JavaScript on the page. 
</p>  


<h2 id="privacy-security"><span class="secno">6 </span>Privacy and Security</h2>

<p>This section is non-normative.</p>

This specification utilizes current standard building blocks of web communication - specifically the HTTP Cookie mechanism. This implies that no additional security and pricacy threats are introduced. 


<p>
</p>


<h2 id="references"><span class="secno">8 </span>References</h2>

<h3 id="normative-references"><span class="secno">8.1 </span>Normative References</h3>

<dl>
<dt><a id="rfc2119">[IETF RFC 2119]</a></dt>
<dd>
 <cite><a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>. 
</dd>
<dt><a id="rfc2616">[IETF RFC 2616]</a></dt>
<dd>
 <cite><a href="http://www.ietf.org/rfc/rfc2616.txt">Hypertext Transfer Protocol -- HTTP/1.1</a></cite>, R. Fielding et al., Authors. Internet Engineering Task Force, June 1999. Available at <a href="http://www.ietf.org/rfc/rfc2616.txt">http://www.ietf.org/rfc/rfc2616.txt</a>. 
</dd>
<dt>[<a id="rfc6454">IETF RFC 6454</a>]</dt>
<dd>
 <cite><a href="http://tools.ietf.org/html/rfc6454">The Web Origin Concept</a></cite>, Adam Barth, Author.  Internet Engineering Task Force, December 2011. Available at <a href="http://www.ietf.org/rfc/rfc6454.txt">http://www.ietf.org/rfc/rfc6454.txt</a>. 
</dd>
<dt>[<a id="ECMA262">ECMA-262</a>]</dt><dd>
	<cite><a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript Language Specification</a></cite>, 5.1
	Edition. ECMA International, Standard
	ECMA-262, June 2011. This version of the ECMAScript
	Language is available from <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">http://www.ecma-international.org/publications/standards/Ecma-262.htm</a>.
    </dd><dt>[<a id="HTML5">HTML5</a>]</dt>
    <dd><cite><a href='http://www.w3.org/TR/html5/'>HTML5</a></cite>, Robin Berjon et al., Editors. World Wide Web Consortium, December 2012. This version of the HTML5 is available from <a href='http://www.w3.org/TR/html5/'>http://www.w3.org/TR/html5/</a>. The <a href='http://www.w3.org/html/wg/drafts/html/CR/'>latest editor's draft</a> of HTML5 is available at http://www.w3.org/html/wg/drafts/html/CR/.</dd>
   <dt>[<a id="WebIDL">Web IDL</a>]</dt>
   <dd><cite><a href="http://www.w3.org/TR/2012/CR-WebIDL-20120419/">Web IDL</a></cite>, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The <a href="http://www.w3.org/TR/WebIDL/">latest version of Web IDL</a> is available at http://www.w3.org/TR/WebIDL/.</dd>
   <dt>[<a id="HighResolutionTime">High Resolution Time</a>]</dt>
   <dd><cite><a href='http://www.w3.org/TR/2012/REC-hr-time-20121217/'>High Resolution Time</a></cite>, Jatinder Mann, Editor. World Wide Web Consortium, December 2012. This version of the High Resolution Time Recommendation is available from http://www.w3.org/TR/2012/REC-hr-time-20121217/. The <a href='http://www.w3.org/TR/hr-time/'>latest version of High Resolution Time</a> is available at http://www.w3.org/TR/hr-time/.</dd>
   <dt>[<a id="PerformanceTimeline">Performance Timeline</a>]</dt>
   <dd><cite><a href='http://www.w3.org/TR/2012/CR-performance-timeline-20120726/'>Performance Timeline</a></cite>, Jatinder Mann, et al, Editors. World Wide Web Consortium, July 2012. This version of the Performance Timeline specification is available from http://www.w3.org/TR/2012/CR-performance-timeline-20120726/. The <a href='http://www.w3.org/TR/performance-timeline/'>latest version of Performance Timeline</a> is available at http://www.w3.org/TR/performance-timeline/.</dd>
    <dt>[<a id="NavigationTiming">Navigation Timing</a>]</dt>
   <dd><cite><a href='http://www.w3.org/TR/2012/REC-navigation-timing-20121217/'>Navigation Timing</a></cite>, Zhiheng Wang, Editor. World Wide Web Consortium, December 2012. This edition of the Navigation Timing Recommendation is available from http://www.w3.org/TR/2012/REC-navigation-timing-20121217/. The <a href='http://www.w3.org/TR/navigation-timing/'>latest version of Navigation Timing</a> is available at http://www.w3.org/TR/navigation-timing/.</dd>
</dl>

</body>
</html>
